Overview

Fixes #235 and hardens reader-thread lifecycle in SubscriptionThreadDispatcher. Frame callbacks now start a reader regardless of when they are registered, replacement actually replaces, and driving the dispatcher from inside a frame callback no longer self-joins. No public API changes — setOn*FrameCallback now does what it always documented.

The bugs

• Late registration never started a reader (Calling setOnVideo/AudioFrameCallback outside of the onTrackSubscribed handler never starts a frame thread handler #235). handleTrackSubscribed ran once, right after RoomDelegate::onTrackSubscribed, and no-oped without a registered callback. Registering afterwards (e.g. from a GUI thread) stored the callback and nothing else happened.
• Replacement was a silent no-op. Reader threads capture the callback by value. Re-registering only overwrote the dispatcher's copy; the running thread kept invoking the old callback.
• Self-joins terminated the process. Room::disconnect() or removeOnDataFrameCallback called from inside a data frame callback joined the calling thread: std::system_error, then a still-joinable std::thread destroyed during unwinding.

Changes

• Retained subscriptions. The dispatcher keeps the subscribed track per (participant, track_name) until unsubscribed, so setOn* starts a reader immediately when the track is already subscribed and defers otherwise. Room also resolves the current publication, which covers registration from inside onTrackSubscribed.
• Replace in place, join before start. Every stop path (setOn*, clearOn*, resubscribe with a new SID, unsubscribe) extracts the reader under the lock, marks the key draining, joins outside the lock, then restarts. No caller can start a reader for a draining key, so old and new callbacks never run concurrently and concurrent setters cannot pile up untracked threads.
• Duplicate subscription events. A repeated track_subscribed for the SID a reader already serves is a no-op; a new SID (republish) stops the old reader first.
• Detach on self-join. No reader lambda captures this; data readers report exit through their own shared state. All readers are therefore safe to detach, so a lifecycle call from inside the reader's own callback logs a warning, detaches, and still takes effect.
• Data track teardown. In-flight RemoteDataTrack::subscribe() calls are marked cancelled so unpublish/republish cannot leave a stale reader or duplicate FFI subscription behind.
• SubscriptionThreadDispatcher deprecated for direct use (LIVEKIT_DEPRECATED); it stays exported to avoid a major bump.

Behavioral notes

• setOn*/clearOn* block until any in-flight invocation of the previous callback returns. A callback that never returns blocks registration indefinitely.
• Re-entrant calls are discouraged but handled. From inside a frame callback for the same key the SDK warns and detaches that reader. The in-flight invocation of the previous callback finishes only after the call returns, so the no-overlap guarantee does not hold for that one invocation.

Public API

No signature changes. include/livekit/room.h changes are documentation only. Callback type aliases moved to include/livekit/frame_callbacks.h (still reachable through room.h).

Test-only: RemoteDataTrack::testFfiHandleId() removed in favor of RemoteDataTrackTestAccess; RoomTestAccess exposes reader/drain counts and retained-subscription state; RemoteDataTrack's private constructor is LIVEKIT_INTERNAL_API so tests can link it.

Testing

• Unit (SubscriptionThreadDispatcherTest, 91): Calling setOnVideo/AudioFrameCallback outside of the onTrackSubscribed handler never starts a frame thread handler #235 in both orderings for audio/video/video-event; replacement semantics including the shared video slot; SID dedup and republish; drain marks set and cleared by every lifecycle path, with starts deferred while draining; self-join handling for setOn*, clearOn*, removeOnDataFrameCallback, and stopAll from both media and data reader threads; data reader cancellation and finished-state handling.
• Integration (FrameCallbackServerTest, 5): the exact Calling setOnVideo/AudioFrameCallback outside of the onTrackSubscribed handler never starts a frame thread handler #235 scenario for video, video-event, and audio; clear-and-re-register without a new event; registration from inside onTrackSubscribed starting exactly one reader.
• Integration (FrameCallbackReplacementTest, 14): delivery switches on replacement; setter blocks for a slow callback without overlapping it; sequential and concurrent churn leave exactly one reader; deferred start and republish; re-entrant setOn*/clearOn*/data removal take effect; Room::disconnect() from inside a data callback.
• Full unit suite (412) and the data-track, room-event, and platform-audio integration suites (37) pass locally against a LiveKit server. clang-format and clang-tidy are clean on the changed files.